package org.convallaria.system.biz.service;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 用户在线状态管理服务
 * 提供用户在线状态检查、管理等功能
 * 
 * @author convallaria
 * @since 1.0.0
 */
public interface UserOnlineService {

    /**
     * 检查用户是否在线
     * 
     * @param userId 用户ID
     * @return 是否在线
     */
    boolean isUserOnline(Long userId);

    /**
     * 设置用户在线状态
     * 
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @param loginIp 登录IP
     * @param userAgent 用户代理
     * @param loginTime 登录时间
     */
    void setUserOnline(Long userId, String sessionId, String loginIp, String userAgent, LocalDateTime loginTime);

    /**
     * 设置用户离线状态
     * 
     * @param userId 用户ID
     * @param sessionId 会话ID
     */
    void setUserOffline(Long userId, String sessionId);

    /**
     * 获取在线用户列表
     * 
     * @param pageNum 页码
     * @param pageSize 页大小
     * @return 在线用户列表
     */
    List<Map<String, Object>> getOnlineUsers(Integer pageNum, Integer pageSize);

    /**
     * 获取在线用户总数
     * 
     * @return 在线用户总数
     */
    long getOnlineUserCount();

    /**
     * 强制用户下线
     * 
     * @param userId 用户ID
     * @param reason 下线原因
     * @return 是否成功
     */
    boolean forceUserOffline(Long userId, String reason);

    /**
     * 检查会话是否有效
     * 
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @return 是否有效
     */
    boolean isSessionValid(Long userId, String sessionId);

    /**
     * 更新用户最后活动时间
     * 
     * @param userId 用户ID
     * @param sessionId 会话ID
     */
    void updateLastActivity(Long userId, String sessionId);

    /**
     * 清理过期会话
     * 
     * @return 清理的会话数量
     */
    int cleanExpiredSessions();

    /**
     * 获取用户会话信息
     * 
     * @param userId 用户ID
     * @return 会话信息
     */
    Map<String, Object> getUserSessionInfo(Long userId);
}
